Skip to content

GenAI Utils | Add _BaseAgent base class and agent creation lifecycle#4217

Closed
etserend wants to merge 13 commits into
open-telemetry:mainfrom
etserend:genai-utils/agent-base-and-creation
Closed

GenAI Utils | Add _BaseAgent base class and agent creation lifecycle#4217
etserend wants to merge 13 commits into
open-telemetry:mainfrom
etserend:genai-utils/agent-base-and-creation

Conversation

@etserend
Copy link
Copy Markdown
Contributor

@etserend etserend commented Feb 19, 2026

Description

The GenAI Utils package includes boilerplate and helpers to standardize instrumentation for Generative AI.

This PR adds the foundational agent type hierarchy and creation lifecycle. It provides a shared _BaseAgent base class and an AgentCreation type, along with TelemetryHandler methods to start, stop, and fail agent creation spans — aligned with the GenAI agent span semantic conventions.

Agent invocation type (invoke_agent), metrics, and events to come in follow-up PRs.

Type of change

  • New feature (non-breaking change which adds functionality)

How Has This Been Tested?

  • Basic unit tests for starting and stopping agent creation spans
  • Unit tests for context manager happy path and error path
  • Unit tests for AgentCreation

Does This PR Require a Core Repo Change?

  • No.

Checklist:

See contributing.md for styleguide, changelog guidelines, and more.

  • Followed the style guidelines of this project
  • Changelogs have been updated
  • Unit tests have been added
  • Documentation has been updated

@etserend etserend force-pushed the genai-utils/agent-base-and-creation branch from e8e9669 to bbcbded Compare February 19, 2026 17:23
Comment thread util/opentelemetry-util-genai/src/opentelemetry/util/genai/handler.py Outdated
Comment thread util/opentelemetry-util-genai/src/opentelemetry/util/genai/handler.py Outdated
Comment thread util/opentelemetry-util-genai/src/opentelemetry/util/genai/span_utils.py Outdated
Comment thread util/opentelemetry-util-genai/src/opentelemetry/util/genai/types.py Outdated
@etserend etserend marked this pull request as ready for review February 23, 2026 15:54
@etserend etserend requested a review from a team as a code owner February 23, 2026 15:54
@tammy-baylis-swi tammy-baylis-swi moved this to Ready for review in Python PR digest Feb 23, 2026
Comment thread util/opentelemetry-util-genai/src/opentelemetry/util/genai/span_utils.py Outdated
Comment thread docs/nitpick-exceptions.ini Outdated
@etserend etserend force-pushed the genai-utils/agent-base-and-creation branch from 8022213 to 0b3acb8 Compare March 6, 2026 21:47
@etserend etserend force-pushed the genai-utils/agent-base-and-creation branch from 0b3acb8 to 0c23956 Compare March 6, 2026 21:55
Comment thread util/opentelemetry-util-genai/src/opentelemetry/util/genai/types.py Outdated
Comment thread util/opentelemetry-util-genai/src/opentelemetry/util/genai/types.py Outdated
Comment thread util/opentelemetry-util-genai/src/opentelemetry/util/genai/types.py Outdated

# ---- Agent lifecycle ----

def start_agent(
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If this goes first will need refactoring.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will refactor as needed

Comment thread util/opentelemetry-util-genai/src/opentelemetry/util/genai/span_utils.py Outdated
Copy link
Copy Markdown
Contributor

@wrisa wrisa left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. Though would need refractoring in case other PRs mentioned in comments are merged first.

Copy link
Copy Markdown
Contributor

@keith-decker keith-decker left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. Thank you!

@etserend
Copy link
Copy Markdown
Contributor Author

Verified the AgentCreation type and TelemetryHandler.create_agent() context manager end-to-end by deploying a LanggraphAgent to Vertex AI Agent Engine.

Demo PR: #4336

Steps exercised:

  • LLM call via google-genai SDK (auto-instrumented by VertexAIInstrumentor)
  • Local agent creation wrapped in create_agent span
  • Remote deploy to Agent Engine wrapped in create_agent span (~4 min)
  • Query the deployed agent (1 USD = 9.2841 SEK)
  • Cleanup (delete agent)
Trace 1:
create_agent Currency Exchange Agent (192µs, Client)
├── gen_ai.agent.description: Local LanggraphAgent for currency exchange
├── gen_ai.agent.name: Currency Exchange Agent
├── gen_ai.operation.name: create_agent
├── gen_ai.provider.name: gcp_vertex_ai
├── gen_ai.request.model: gemini-2.5-flash
└── server.address: us-central1-aiplatform.googleapis.com

Trace 2:
create_agent Currency Exchange Agent (4m5s, Client)
├── gen_ai.agent.description: Deploying agent to Vertex AI Agent Engine
├── gen_ai.agent.name: Currency Exchange Agent
├── gen_ai.operation.name: create_agent
├── gen_ai.provider.name: gcp_vertex_ai
├── gen_ai.request.model: gemini-2.5-flash
└── server.address: us-central1-aiplatform.googleapis.com

Copy link
Copy Markdown
Member

@Cirilla-zmh Cirilla-zmh left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. But it's suggested to get #4219 merged first.

@lzchen lzchen added the gen-ai Related to generative AI label Apr 30, 2026
@lzchen
Copy link
Copy Markdown
Contributor

lzchen commented Apr 30, 2026

@etserend

Are you still working on this? Looks like there were some additions to genai-utils that you might have to rebase on.

@etserend
Copy link
Copy Markdown
Contributor Author

etserend commented May 1, 2026

@etserend

Are you still working on this? Looks like there were some additions to genai-utils that you might have to rebase on.

@lzchen Thanks for checking in. Per the SIG meeting, we're holding off on this implementation for now. I'll update the PR when we're ready to move forward.

@lmolkova
Copy link
Copy Markdown
Member

thanks for the contribution @etserend !

We're moving GenAI instrumentations to the new repository - https://github.com/open-telemetry/opentelemetry-python-genai.

I'm closing this PR here, but you're welcome to reopen it in the new repo.

@lmolkova lmolkova closed this May 13, 2026
@github-project-automation github-project-automation Bot moved this from Ready for review to Done in Python PR digest May 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

gen-ai Related to generative AI

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

10 participants